How To Work With Subscription Model Order Line
The subscription model order line is a dedicated order line used to provide us with details about the agreement when initiating it. The order line is mandatory for some specifics integrations. Hence, it's strongly recommended to always include it in your requests to have a future-proof integration.
This order line will be used for the subsequent charges when no other order lines will be provided during /chargeSubscription or /reserveSubscriptionCharge.
Value |
Description |
|---|---|
itemId |
This value is used to display the agreement main service or product. It's recommended to have a human readable value.
|
description |
This value is used as a more details short description of the agreement.
|
quantity |
This value has to be set to 1. The parameter is mandatory due to backward compatibility reasons. |
unitPrice |
This value represents the agreement default amount for the subsequent charges. A tax amount will be added to the default amount if any provided as part of this order line.
The default subscription amount will be 349.00 DKK. This value has to match with the payment request amount except for one-off payments. In case of using subscriptionAndCharge or subscriptionAndReserve with the intention of charging the agreement right away, please use the same amount here as the one in the payment request. |
goodsType |
subscription_model - Fixed value. Only a single order line of this type is accepted. |
See more details here
Setup Agreement With Initial Charge/One-Off
Our solution offers you various ways to accommodate your business case as they are described below.
Setup an Agreement With Free Trial Period
This use case can be achieved by setting up an agreement with your consumer without charging it right away. You'll have to send the charge request after the free trial period ends.
- Initiate the agreement using /createPaymentRequest or /setupSubscription.
- Charge it at the end of free trial period using /chargeSubscription or /reserveSubscriptionCharge depending on your case.
The merchant is in charge of capturing the reservations initiated with /reserveSubscriptionCharge by using /captureReservation.
How to initiate an agreement
curl --request POST \ --url https://<YourShopName>.altapaysecure.com/merchant/API/createPaymentRequest \ --header 'Authorization: Basic XXX' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data shop_orderid=abc123 \ --data type=subscription \ --data 'terminal=Pensio Terminal' \ --data amount=50.00 \ --data currency=EUR \ --data 'agreement[type]=recurring' \ --data 'agreement[frequency]=30' \ --data 'orderLines[0][itemId]=Internet Service' \ --data 'orderLines[0][description]=Basic Plan' \ --data 'orderLines[0][quantity]=1' \ --data 'orderLines[0][goodsType]=subscription_model' \ --data 'orderLines[0][unitPrice]=50.00'
How to charge it at the end of the free trial period
curl --request POST \ --url https://<YourShopName>.altapaysecure.com/merchant/API/chargeSubscription \ --header 'Authorization: Basic XXX' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'agreement[id]=<PaymentId>'
Setup an Agreement & Charge It Right-Away
This use case allows you to charge your consumer right away after setting up an agreement. This can be done in a single step by providing the type during the request:
- subscriptionAndCharge - to capture the first instalment payment of the agreement.
- subscriptionAndReserve - to reserve the first instalment payment of the agreement.
curl --request POST \ --url https://<YourShopName>.altapaysecure.com/merchant/API/createPaymentRequest \ --header 'Authorization: Basic XXX' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data shop_orderid=abc123 \ --data type=subscriptionAndCharge \ --data 'terminal=Pensio Terminal' \ --data amount=50.00 \ --data currency=EUR \ --data 'agreement[type]=recurring' \ --data 'agreement[frequency]=30' \ --data 'orderLines[0][itemId]=Internet Service' \ --data 'orderLines[0][description]=Basic Plan' \ --data 'orderLines[0][quantity]=1' \ --data 'orderLines[0][goodsType]=subscription_model' \ --data 'orderLines[0][unitPrice]=50.00'
Setup an Agreement With Initial One-Off Payment
This use case is allowing you to setup an agreement for a service with your consumer, and to let him make a purchase for other goods in the same time.
The customer will have an improved experience because they'll approve the agreement and the payment only once.
The initial one-off payment is a single payment that might not be related to the agreement itself.
The agreement will be set using the itemId, description & amount from the subscription model order line. Moreover, the payment request amount and the other order lines provided will be used for the one-off payment.
This feature is activated by providing one of these two values as auth type: subscriptionAndCharge and subscriptionAndReserve.
curl --request POST \ --url https://<YourShopName>.altapaysecure.com/merchant/API/createPaymentRequest \ --header 'Authorization: Basic XXX' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'terminal=AltaPay Terminal' \ --data shop_orderid=abc123 \ --data amount=557.60 \ --data currency=DKK \ --data type=subscriptionAndReserve \ --data 'agreement[type]=recurring' \ --data 'agreement[frequency]=30' \ --data 'orderLines[0][itemId]=Internet' \ --data 'orderLines[0][description]=Basic Subscription' \ --data 'orderLines[0][quantity]=1' \ --data 'orderLines[0][goodsType]=subscription_model' \ --data 'orderLines[0][unitPrice]=399.00' \ --data 'orderLines[1][itemId]=2367171' \ --data 'orderLines[1][description]=Router' \ --data 'orderLines[1][quantity]=1' \ --data 'orderLines[1][goodsType]=item' \ --data 'orderLines[1][unitPrice]=409.00' \ --data 'orderLines[2][itemId]=7247247' \ --data 'orderLines[2][description]=Cables' \ --data 'orderLines[2][quantity]=1' \ --data 'orderLines[2][goodsType]=item' \ --data 'orderLines[2][unitPrice]=59.60' \ --data 'orderLines[3][itemId]=247246' \ --data 'orderLines[3][description]=VPN Device' \ --data 'orderLines[3][quantity]=1' \ --data 'orderLines[3][goodsType]=item' \ --data 'orderLines[3][unitPrice]=99.00' \ --data 'customer_info[customer_phone]=+4559752955'
By following the example above, we're going to have an agreement set for 399 DKK and a one-off payment of 557.6 DKK composed by the other order lines besides the subscription model one.
If you want to charge the agreement as well right after, please use /chargeSubscription or /reserveSubscriptionCharge to do it.
You can either provide order lines or rely on the original subscription model one from the first request.